<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This file documents the use of the GNU compilers.

Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>Return Address (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="Return Address (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Return Address (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Indices.html" rel="index" title="Indices">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="C-Extensions.html" rel="up" title="C Extensions">
<link href="Vector-Extensions.html" rel="next" title="Vector Extensions">
<link href="Function-Names.html" rel="prev" title="Function Names">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
kbd.key {font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>


</head>

<body lang="en_US">
<div class="section-level-extent" id="Return-Address">
<div class="nav-panel">
<p>
Next: <a href="Vector-Extensions.html" accesskey="n" rel="next">Using Vector Instructions through Built-in Functions</a>, Previous: <a href="Function-Names.html" accesskey="p" rel="prev">Function Names as Strings</a>, Up: <a href="C-Extensions.html" accesskey="u" rel="up">Extensions to the C Language Family</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Getting-the-Return-or-Frame-Address-of-a-Function"><span>6.51 Getting the Return or Frame Address of a Function<a class="copiable-link" href="#Getting-the-Return-or-Frame-Address-of-a-Function"> &para;</a></span></h3>

<p>These functions may be used to get information about the callers of a
function.
</p>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fbuiltin_005freturn_005faddress"><span class="category-def">Built-in Function: </span><span><code class="def-type">void *</code> <strong class="def-name">__builtin_return_address</strong> <code class="def-code-arguments">(unsigned int <var class="var">level</var>)</code><a class="copiable-link" href="#index-_005f_005fbuiltin_005freturn_005faddress"> &para;</a></span></dt>
<dd><p>This function returns the return address of the current function, or of
one of its callers.  The <var class="var">level</var> argument is number of frames to
scan up the call stack.  A value of <code class="code">0</code> yields the return address
of the current function, a value of <code class="code">1</code> yields the return address
of the caller of the current function, and so forth.  When inlining
the expected behavior is that the function returns the address of
the function that is returned to.  To work around this behavior use
the <code class="code">noinline</code> function attribute.
</p>
<p>The <var class="var">level</var> argument must be a constant integer.
</p>
<p>On some machines it may be impossible to determine the return address of
any function other than the current one; in such cases, or when the top
of the stack has been reached, this function returns an unspecified
value.  In addition, <code class="code">__builtin_frame_address</code> may be used
to determine if the top of the stack has been reached.
</p>
<p>Additional post-processing of the returned value may be needed, see
<code class="code">__builtin_extract_return_addr</code>.
</p>
<p>The stored representation of the return address in memory may be different
from the address returned by <code class="code">__builtin_return_address</code>.  For example,
on AArch64 the stored address may be mangled with return address signing
whereas the address returned by <code class="code">__builtin_return_address</code> is not.
</p>
<p>Calling this function with a nonzero argument can have unpredictable
effects, including crashing the calling program.  As a result, calls
that are considered unsafe are diagnosed when the <samp class="option">-Wframe-address</samp>
option is in effect.  Such calls should only be made in debugging
situations.
</p>
<p>On targets where code addresses are representable as <code class="code">void *</code>,
</p><div class="example smallexample">
<pre class="example-preformatted">void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
</pre></div>
<p>gives the code address where the current function would return.  For example,
such an address may be used with <code class="code">dladdr</code> or other interfaces that work
with code addresses.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fbuiltin_005fextract_005freturn_005faddr"><span class="category-def">Built-in Function: </span><span><code class="def-type">void *</code> <strong class="def-name">__builtin_extract_return_addr</strong> <code class="def-code-arguments">(void *<var class="var">addr</var>)</code><a class="copiable-link" href="#index-_005f_005fbuiltin_005fextract_005freturn_005faddr"> &para;</a></span></dt>
<dd><p>The address as returned by <code class="code">__builtin_return_address</code> may have to be fed
through this function to get the actual encoded address.  For example, on the
31-bit S/390 platform the highest bit has to be masked out, or on SPARC
platforms an offset has to be added for the true next instruction to be
executed.
</p>
<p>If no fixup is needed, this function simply passes through <var class="var">addr</var>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fbuiltin_005ffrob_005freturn_005faddr"><span class="category-def">Built-in Function: </span><span><code class="def-type">void *</code> <strong class="def-name">__builtin_frob_return_addr</strong> <code class="def-code-arguments">(void *<var class="var">addr</var>)</code><a class="copiable-link" href="#index-_005f_005fbuiltin_005ffrob_005freturn_005faddr"> &para;</a></span></dt>
<dd><p>This function does the reverse of <code class="code">__builtin_extract_return_addr</code>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-_005f_005fbuiltin_005fframe_005faddress"><span class="category-def">Built-in Function: </span><span><code class="def-type">void *</code> <strong class="def-name">__builtin_frame_address</strong> <code class="def-code-arguments">(unsigned int <var class="var">level</var>)</code><a class="copiable-link" href="#index-_005f_005fbuiltin_005fframe_005faddress"> &para;</a></span></dt>
<dd><p>This function is similar to <code class="code">__builtin_return_address</code>, but it
returns the address of the function frame rather than the return address
of the function.  Calling <code class="code">__builtin_frame_address</code> with a value of
<code class="code">0</code> yields the frame address of the current function, a value of
<code class="code">1</code> yields the frame address of the caller of the current function,
and so forth.
</p>
<p>The frame is the area on the stack that holds local variables and saved
registers.  The frame address is normally the address of the first word
pushed on to the stack by the function.  However, the exact definition
depends upon the processor and the calling convention.  If the processor
has a dedicated frame pointer register, and the function has a frame,
then <code class="code">__builtin_frame_address</code> returns the value of the frame
pointer register.
</p>
<p>On some machines it may be impossible to determine the frame address of
any function other than the current one; in such cases, or when the top
of the stack has been reached, this function returns <code class="code">0</code> if
the first frame pointer is properly initialized by the startup code.
</p>
<p>Calling this function with a nonzero argument can have unpredictable
effects, including crashing the calling program.  As a result, calls
that are considered unsafe are diagnosed when the <samp class="option">-Wframe-address</samp>
option is in effect.  Such calls should only be made in debugging
situations.
</p></dd></dl>

</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Vector-Extensions.html">Using Vector Instructions through Built-in Functions</a>, Previous: <a href="Function-Names.html">Function Names as Strings</a>, Up: <a href="C-Extensions.html">Extensions to the C Language Family</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
